Nuxt Studio Setup and Deployment

Overview

Nuxt Studio is a free, open-source visual content editor for Nuxt Content websites that enables content editing directly in production. It provides multiple editor types (Monaco code editor, TipTap visual WYSIWYG editor, Form-based editor), OAuth authentication (GitHub/GitLab/Google), and Git-based content management with commit integration.

Primary use case

Add visual CMS capabilities to existing Nuxt Content websites, typically deployed to a subdomain like

studio.domain.com

or

cms.domain.com

.

When to Use This Skill

Use this skill when users need to:

Set up Nuxt Studio for the first time on a Nuxt Content website

Configure OAuth authentication for Studio access

Deploy Studio to Cloudflare Pages or Workers with custom subdomain

Troubleshoot Studio authentication, build, or deployment issues

Configure editor types or customize Studio behavior

Integrate Studio with existing Nuxt v3/v4 applications

Prerequisites Check

Before proceeding with Studio setup, verify these requirements:

Nuxt Version

≥3.x (Studio requires Nuxt 3)

@nuxt/content Module

≥2.x (required dependency)

Node.js

≥18.x recommended

Cloudflare Account

Required for Cloudflare deployment (optional for other platforms) Check Nuxt Content installation :

Verify @nuxt/content is installed

grep "@nuxt/content" package.json

Check nuxt.config.ts for content module

grep "modules.*content" nuxt.config.ts If Nuxt Content is not installed, install it first: npx nuxi module add content Installation 1. Install Nuxt Studio Module Install the latest beta version (v1.0.0-beta.3 as of December 2025): npx nuxi module add nuxt-studio@beta This adds @nuxt/studio to devDependencies and configures the module in nuxt.config.ts . 2. Verify Module Configuration Check that nuxt.config.ts includes the Studio module: // nuxt.config.ts export default defineNuxtConfig ( { modules : [ '@nuxt/content' , '@nuxt/studio' // Added automatically ] } ) 3. Start Development Mode Run the development server to test Studio locally: npm run dev

or

bun dev

Access Studio at

http://localhost:3000/_studio

(development mode).

OAuth Authentication Setup

Studio requires OAuth authentication for production deployments. Choose one provider:

Supported Providers

GitHub OAuth

Best for public repositories and GitHub-hosted projects

GitLab OAuth

Ideal for self-hosted GitLab instances

Google OAuth

Universal option for any setup Quick OAuth Configuration For detailed OAuth setup instructions for each provider, load references/oauth-providers.md . Environment variables pattern (all providers):

GitHub

NUXT_OAUTH_GITHUB_CLIENT_ID

your_client_id NUXT_OAUTH_GITHUB_CLIENT_SECRET = your_client_secret

GitLab

NUXT_OAUTH_GITLAB_CLIENT_ID

your_client_id NUXT_OAUTH_GITLAB_CLIENT_SECRET = your_client_secret

Google

NUXT_OAUTH_GOOGLE_CLIENT_ID

your_client_id

NUXT_OAUTH_GOOGLE_CLIENT_SECRET

=

your_client_secret

Callback URL pattern

:

https://studio.yourdomain.com/api/auth/callback/[provider]

Replace

[provider]

with:

github

,

gitlab

, or

google

.

For complete OAuth app creation steps, consult

references/oauth-providers.md

.

Cloudflare Deployment

Studio works excellently on Cloudflare Pages and Workers. Use the Cloudflare deployment for:

Serverless edge deployment

Custom subdomain routing (e.g.,

studio.domain.com

)

Environment variable management via dashboard

Automatic builds from Git

Cloudflare Setup Overview

Configure Nitro preset

for Cloudflare in

nuxt.config.ts

Create or update

wrangler.toml

for Workers deployment (optional)

Set environment variables

on Cloudflare dashboard

Configure custom domain

and subdomain routing

Deploy

via Cloudflare Pages or Workers

For complete Cloudflare deployment instructions, load

references/cloudflare-deployment.md

.

Quick Cloudflare Configuration

Set the Cloudflare Pages preset:

// nuxt.config.ts

export

default

defineNuxtConfig

(

{

modules

:

[

'@nuxt/content'

,

'@nuxt/studio'

]

,

nitro

:

{

preset

:

'cloudflare-pages'

}

}

)

For Workers deployment with custom subdomain routing, see

references/cloudflare-deployment.md

.

Editor Types

Studio provides three editor types that can be configured per content type:

Monaco Editor

Code editor for markdown, YAML, JSON

TipTap Editor

Visual WYSIWYG editor with MDC component support (default)

Form Editor

Schema-driven form for YAML/JSON files

Configure Default Editor

// nuxt.config.ts

export

default

defineNuxtConfig

(

{

studio

:

{

editor

:

{

default

:

'tiptap'

// or 'monaco' or 'form'

}

}

}

)

For detailed editor configuration options, load

references/editor-configuration.md

.

Subdomain Configuration

Deploy Studio to a subdomain for production use:

Common patterns

:

studio.yourdomain.com

cms.yourdomain.com

edit.yourdomain.com

admin.yourdomain.com

DNS Setup

Add a CNAME record in your DNS provider

Point subdomain to Cloudflare Pages deployment

Configure custom domain in Cloudflare Pages settings

For complete subdomain setup with Cloudflare, load

references/subdomain-setup.md

.

Top 5 Common Errors

1. OAuth Redirect URI Mismatch

Error

Authentication loop or "redirect_uri_mismatch" error

Cause

OAuth app callback URL doesn't match actual deployment URL

Solution

:

Ensure OAuth app callback URL is:

https://studio.yourdomain.com/api/auth/callback/[provider]

Not:

https://yourdomain.com/api/auth/callback/[provider]

2. Module Not Found: @nuxt/studio

Error

:

Cannot find module '@nuxt/studio'

Cause

Studio module not installed or installed incorrectly Solution : npx nuxi module add nuxt-studio@beta

or

npm

install

-D

@nuxt/studio

3. Cloudflare Pages Build Failure

Error

Build fails with "Incompatible module" or runtime errors

Cause

Nitro preset not configured for Cloudflare

Solution

:

// nuxt.config.ts

export

default

defineNuxtConfig

(

{

nitro

:

{

preset

:

'cloudflare-pages'

}

}

)

4. Authentication Loop After Login

Error

Redirects to login repeatedly after successful OAuth

Cause

Session cookies not persisting due to domain mismatch

Solution

:

Verify

NUXT_PUBLIC_STUDIO_URL

environment variable matches deployment URL

Check cookie settings in browser (must allow third-party cookies for OAuth)

Ensure deployment URL uses HTTPS (not HTTP)

5. Subdomain Routing Not Working

Error

Studio loads on main domain instead of subdomain

Cause

DNS/wrangler configuration incorrect

Solution

:

Verify CNAME record points to Cloudflare Pages

Check custom domain configuration in Cloudflare dashboard

For Workers: verify

wrangler.toml

routes configuration

For complete error catalog and solutions, load

references/troubleshooting.md

.

Working with Templates

The skill includes working configuration templates:

templates/nuxt.config.ts

Complete Studio module configuration

templates/wrangler.toml

Cloudflare Workers deployment config

templates/studio-auth-github.ts

GitHub OAuth implementation

templates/studio-auth-gitlab.ts

GitLab OAuth implementation

templates/studio-auth-google.ts

Google OAuth implementation

Use these as starting points for your Studio setup.

Development Workflow

Local Development

Install Studio module:

npx nuxi module add nuxt-studio@beta

Start dev server:

npm run dev

Access Studio:

http://localhost:3000/_studio

Edit content visually

Commit changes from Studio UI

Production Deployment

Configure OAuth provider (GitHub/GitLab/Google)

Set environment variables on deployment platform

Configure Nitro preset for target platform

Deploy to Cloudflare Pages/Workers or other platform

Set up custom subdomain

Test authentication and content editing

Validation Checklist

Before deploying Studio to production:

Nuxt Content installed and configured (≥v2.x)

Nuxt version ≥3.x

@nuxt/studio module installed

OAuth provider configured with valid credentials

Environment variables set correctly

Nitro preset configured for deployment platform

Custom subdomain DNS configured

Callback URLs match deployment URL

Studio accessible at subdomain URL

Authentication working correctly

Content editing and commit functionality tested

When to Load References

Load reference files when working on specific aspects:

OAuth setup

Load

references/oauth-providers.md

for detailed GitHub/GitLab/Google OAuth app creation

Cloudflare deployment

Load

references/cloudflare-deployment.md

for complete Cloudflare Pages/Workers setup with wrangler, custom domains, and environment variables

Editor configuration

Load

references/editor-configuration.md

for Monaco/TipTap/Form editor customization

Subdomain setup

Load

references/subdomain-setup.md

for DNS and routing configuration

Troubleshooting

Load

references/troubleshooting.md

for comprehensive error solutions and debugging

Utility Scripts

Use the included scripts for common operations:

scripts/check-prerequisites.sh

Verify Nuxt Content and version requirements

scripts/validate-config.sh

Check nuxt.config.ts Studio configuration

scripts/test-oauth.sh

Test OAuth environment variables setup

Run scripts with:

bash

$CLAUDE_PLUGIN_ROOT

/skills/nuxt-studio/scripts/script-name.sh

Integration with Other Skills

This skill works well with:

nuxt-content

Prerequisites for Studio (content module required)

nuxt-v4

Core Nuxt framework knowledge for configuration

cloudflare-worker-base

Cloudflare deployment fundamentals

better-auth

Alternative authentication patterns if custom auth needed

Additional Resources

Nuxt Studio Repository

:

https://github.com/nuxt-content/studio

Nuxt Content Documentation

:

https://content.nuxt.com

Cloudflare Pages

:

https://pages.cloudflare.com

OAuth Documentation

GitHub/GitLab/Google developer docs

Version Information

Nuxt Studio

v1.0.0-beta.3 (latest as of December 2025)

Nuxt

≥3.x required

@nuxt/content

≥2.x required

Node.js

≥18.x recommended

For the latest version information, check:

https://github.com/nuxt-content/studio/releases

Next steps

After Studio is configured, test the deployment thoroughly, ensure OAuth authentication works correctly, and verify that content editing and Git commits function as expected.